HuasoFoundries / backgrid_es6

  backbone.paginator

  http://github.com/backbone-paginator/backbone.paginator

  Copyright (c) 2016 Jimmy Yuen Ho Wong and contributors

  @module

  @license MIT

*/

import Backbone from 'backbone';

/**

   __BROWSER ONLY__

   If you already have an object named `PageableCollection` attached to the

   `Backbone` module, you can use this to return a local reference to this

   PageableCollection class and reset the name PageableCollection to its

   previous definition.

       // The left hand side gives you a reference to this

       // PageableCollection implementation, the right hand side

       // resets PageableCollection to your other PageableCollection.

       var PageableCollection = PageableCollection.noConflict();

   @static

   @return {PageableCollection}

*/

var _extend = _.extend;

var _omit = _.omit;

var _clone = _.clone;

var _each = _.each;

var _pick = _.pick;

var _contains = _.contains;

var _isEmpty = _.isEmpty;

var _pairs = _.pairs;

var _invert = _.invert;

var _isArray = _.isArray;

var _isFunction = _.isFunction;

var _isObject = _.isObject;

var _keys = _.keys;

var _isUndefined = _.isUndefined;

var ceil = Math.ceil;

var floor = Math.floor;

var max = Math.max;

var BBColProto = Backbone.Collection.prototype;

function finiteInt(val, name) {

    throw new TypeError("`" + name + "` must be a finite integer");

  }

  return val;

}

function queryStringToParams(qs) {

  var kvp, k, v, ls, params = {},

  var kvps = qs.split('&');

  for (var i = 0, l = kvps.length; i < l; i++) {

    var param = kvps[i];

  }

  return params;

}

// hack to make sure the whatever event handlers for this event is run

// before func is, and the event handlers that func will trigger.

function runOnceAtLastHandler(col, event, func) {

  var eventHandlers = col._events[event];

  if (eventHandlers && eventHandlers.length) {

    var lastHandler = eventHandlers[eventHandlers.length - 1];

    var oldCallback = lastHandler.callback;

    lastHandler.callback = function () {

      try {

        oldCallback.apply(this, arguments);

        func();

      } catch (e) {

        throw e;

      } finally {

        lastHandler.callback = oldCallback;

      }

    };

}

var PARAM_TRIM_RE = /[\s'"]/g;

var URL_TRIM_RE = /[<>\s'"]/g;

/**

 * State change event. Fired when PageableCollection#state gets updated

 *

 * @event pageable:state:change

 * @type {object} The PageableCollection#state object of this

 * PageableCollection instance

 */

/**

   Drop-in replacement for Backbone.Collection. Supports server-side and

   client-side pagination and sorting. Client-side mode also support fully

   multi-directional synchronization of changes between pages.

   @class PageableCollection

   @extends Backbone.Collection

*/

var PageableCollection = Backbone.Collection.extend({

  /**

     The container object to store all pagination states.

     You can override the default state by extending this class or specifying

     them in an `options` hash to the constructor.

     @property {number} firstPage = 1 - The first page index. Set to 0 if

     your server API uses 0-based indices. You should only override this value

     during extension, initialization or reset by the server after

     fetching. This value should be read only at other times.

     @property {number} lastPage = null - The last page index. This value

     is __read only__ and it's calculated based on whether `firstPage` is 0 or

     1, during bootstrapping, fetching and resetting. Please don't change this

     value under any circumstances.

     @property {number} currentPage = null - The current page index. You

     should only override this value during extension, initialization or reset

     by the server after fetching. This value should be read only at other

     times. Can be a 0-based or 1-based index, depending on whether

     `firstPage` is 0 or 1. If left as default, it will be set to `firstPage`

     on initialization.

     @property {number} pageSize = 25 - How many records to show per

     page. This value is __read only__ after initialization, if you want to

     change the page size after initialization, you must call

     PageableCollection#setPageSize.

     @property {number} totalPages = null - How many pages there are. This

     value is __read only__ and it is calculated from `totalRecords`.

     @property {number} totalRecords = null - How many records there

     are. This value is __required__ under server mode. This value is optional

     for client mode as the number will be the same as the number of models

     during bootstrapping and during fetching, either supplied by the server

     in the metadata, or calculated from the size of the response.

     @property {string} sortKey = null - The model attribute to use for

     sorting.

     @property {number} order = -1 - The order to use for sorting. Specify

     -1 for ascending order or 1 for descending order. If 0, no client side

     sorting will be done and the order query parameter will not be sent to

     the server during a fetch.

  */

  state: {

    firstPage: 1,

    lastPage: null,

    currentPage: null,

    pageSize: 25,

    totalPages: null,

    totalRecords: null,

    sortKey: null,

    order: -1

  },

  /**

     @property {string} mode = "server" The mode of operations for this

     collection. `"server"` paginates on the server-side, `"client"` paginates

     on the client-side and `"infinite"` paginates on the server-side for APIs

     that do not support `totalRecords`.

  */

  mode: "server",

  /**

     A translation map to convert PageableCollection state attributes

     to the query parameters accepted by your server API.

     You can override the default state by extending this class or specifying

     them in `options.queryParams` object hash to the constructor.

     @property {string} currentPage = "page"

     @property {string} pageSize = "per_page"

     @property {string} totalPages = "total_pages"

     @property {string} totalRecords = "total_entries"

     @property {string} sortKey = "sort_by"

     @property {string} order = "order"

     @property {string} directions = {"-1": "asc", "1": "desc"} - A map for

     translating a PageableCollection#state.order constant to the ones your

     server API accepts.

  */

  queryParams: {

    currentPage: "page",

    pageSize: "per_page",

    totalPages: "total_pages",

    totalRecords: "total_entries",

    sortKey: "sort_by",

    order: "order",

    directions: {

      "-1": "asc",

      "1": "desc"

    }

  },

  /**

     Given a list of models or model attributues, bootstraps the full

     collection in client mode or infinite mode, or just the page you want in

     server mode.

     If you want to initialize a collection to a different state than the

     default, you can specify them in `options.state`. Any state parameters

     supplied will be merged with the default. If you want to change the

     default mapping from PageableCollection#state keys to your server API's

     query parameter names, you can specifiy an object hash in

     `option.queryParams`. Likewise, any mapping provided will be merged with

     the default. Lastly, all Backbone.Collection constructor options are also

     accepted.

     See:

     - PageableCollection#state

     - PageableCollection#queryParams

     - [Backbone.Collection#initialize](http://backbonejs.org/#Collection-constructor)

     @constructor

     @property {Backbone.Collection} fullCollection - __CLIENT MODE ONLY__

     This collection is the internal storage for the bootstrapped or fetched

     models. You can use this if you want to operate on all the pages.

     @param {Array.<Object>} models

     @param {Object} options

     @param {function(*, *): number} options.comparator - If specified, this

     comparator is set to the current page under server mode, or the

     PageableCollection#fullCollection otherwise.

     @param {boolean} options.full 0 If `false` and either a

     `options.comparator` or `sortKey` is defined, the comparator is attached

     to the current page. Default is `true` under client or infinite mode and

     the comparator will be attached to the PageableCollection#fullCollection.

     @param {Object} options.state - The state attributes overriding the defaults.

     @param {string} options.state.sortKey - The model attribute to use for

     sorting. If specified instead of `options.comparator`, a comparator will

     be automatically created using this value, and optionally a sorting order

     specified in `options.state.order`. The comparator is then attached to

     the new collection instance.

     @param {number} options.state.order - The order to use for sorting. Specify

     -1 for ascending order and 1 for descending order.

     @param {Object} options.queryParam

  */

  constructor: function (models, options) {

    BBColProto.constructor.apply(this, arguments);

    options = options || {};

      options.queryParams || {});

    queryParams.directions = _extend({},

      this.queryParams.directions,

      queryParams.directions);

    this.queryParams = queryParams;

      options.state);

      state.firstPage :

      state.currentPage;

    models = models.slice();

      state.totalRecords = models.length;

    }

    this.switchMode(mode, _extend({

      fetch: false,

      resetState: false,

      models: models

    }, options));

    var comparator = options.comparator;

    if (state.sortKey && !comparator) {

      this.setSorting(state.sortKey, state.order, options);

    }

      var fullCollection = this.fullCollection;

      if (comparator && options.full) {

        this.comparator = null;

        fullCollection.comparator = comparator;

      }

      // make sure the models in the current page and full collection have the

      // same references

      if (!_isEmpty(models)) {

        this.reset(models, _extend({

          silent: true

        }, options));

        this.getPage(state.currentPage);

        models.splice.apply(models, [0, models.length].concat(this.models));

      }

    }

    this._initState = _clone(this.state);

  },

  /**

     Makes a Backbone.Collection that contains all the pages.

     @private

     @param {Array.<Object|Backbone.Model>} models

     @param {Object} options Options for Backbone.Collection constructor.

     @return {Backbone.Collection}

  */

  _makeFullCollection: function (models, options) {

    var properties = ["url", "model", "sync", "comparator"];

    var thisProto = this.constructor.prototype;

    var i, length, prop;

    var proto = {};

    for (i = 0, length = properties.length; i < length; i++) {

      prop = properties[i];

      if (!_isUndefined(thisProto[prop])) {

        proto[prop] = thisProto[prop];

      }

    }

    for (i = 0, length = properties.length; i < length; i++) {

      prop = properties[i];

      if (this[prop] !== thisProto[prop]) {

        fullCollection[prop] = this[prop];

      }

    }

    return fullCollection;

  },

  /**

     Factory method that returns a Backbone event handler that responses to

     the `add`, `remove`, `reset`, and the `sort` events. The returned event

     handler will synchronize the current page collection and the full

     collection's models.

     @private

     @fires PageableCollection#pageable:state:change when handling an

     `add`, `remove`, or `reset` event

     @param {PageableCollection} pageCol

     @param {Backbone.Collection} fullCol

     @return {function(string, Backbone.Model, Backbone.Collection, Object)}

     Collection event handler

  */

  /**

     Sanity check this collection's pagination states. Only perform checks

     when all the required pagination state values are defined and not null.

     If `totalPages` is undefined or null, it is set to `totalRecords` /

     `pageSize`. `lastPage` is set according to whether `firstPage` is 0 or 1

     when no error occurs.

     @private

     @throws {TypeError} If `totalRecords`, `pageSize`, `currentPage` or

     `firstPage` is not a finite integer.

     @throws {RangeError} If `pageSize`, `currentPage` or `firstPage` is out

     of bounds.

     @return {Object} Returns the `state` object if no error was found.

  */

  _checkState: function (state) {

    var mode = this.mode;

    var links = this.links;

    var totalRecords = state.totalRecords;

    var pageSize = state.pageSize;

    var currentPage = state.currentPage;

    var firstPage = state.firstPage;

    var totalPages = state.totalPages;